'\" t
.\"     Title: bugle-camera
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: October 2007
.\"    Manual: Bugle user manual
.\"    Source: BUGLE 0.0.20150628
.\"  Language: English
.\"
.TH "BUGLE\-CAMERA" "7" "October 2007" "BUGLE 0.0.20150628" "Bugle user manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bugle-camera \- allow the camera to be manipulated
.SH "SYNOPSIS"
.sp
.nf
filterset camera [\fIkey\fR inactive]
{
    \fBspeed\fR "\fI1\&.0\fR"
    \fBmouse_dga\fR "\fIno\fR"
}
.fi
.SH "DESCRIPTION"
.PP
This filter\-set allows you to take over the camera in an OpenGL application and move it about\&. This is particularly useful for testing visibility culling and level\-of\-detail (LOD), as these will not change as the camera is moved\&.
.PP
To use it, make sure it is activated, then move to the mouse to control the camera angle and the
Up,
Down,
Left
and
Right
keys to move the viewpoint\&. The camera model is a free camera, so it will not maintain a defined up direction\&. There are a few other useful keys, described in
the section called \(lqOPTIONS\(rq\&.
.PP
This filter\-set supports activation and deactivation; the recommended use is to have it initially inactive and use a key to take over control when desired (see
\fBbugle\fR(3))\&.
.PP
Since this filter\-set is based on modifying OpenGL state without telling the application, there are significant limitations:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The projection matrix, and in particular, the near and far clip planes, are not altered\&. Thus, trying to move in too close or out too far could cause objects to be clipped away\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Various fancy rendering techniques involve rendering a quad that is carefully aligned to the screen; altering the camera will break such techniques\&. There is ultimately no general fix as it is impossible to know when an application is dealing with the real world\&. If you are writing such an application and wish it to work with this filter\-set, you should use a vertex program that ignores the model\-view matrix in situations where you do not want this filter\-set to interfere\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Applications that rely on the feedback buffer are likely to break\&.
.RE
.SH "OPTIONS"
.PP
\fBmouse_dga\fR
.RS 4
This is a boolean option which should be enabled when debugging an application that uses
\fBXDGA\fR(3)
to get relative motion data from the mouse\&. If the camera goes all over the place as soon as you move the mouse, try enabling this option (SDL\-based applications are the main culprits)\&.
.RE
.PP
\fBspeed\fR
.RS 4
This sets the speed at which the camera moves\&. Since each application has a different scale, you will need to adjust the value for each application (but dynamic control is also possible; see below)\&.
.RE
.PP
\fBkey_forward\fR, \fBkey_back\fR, \fBkey_left\fR, \fBkey_right\fR
.RS 4
These are the keys for moving the camera\&. They default to the arrow keys\&.
.RE
.PP
\fBkey_faster\fR, \fBkey_slower\fR
.RS 4
These keys control the speed of the camera, doubling or halving it respectively\&. They default to
PageUp
and
PageDown\&.
.RE
.PP
\fBkey_reset\fR
.RS 4
This key cancels any alterations made, restoring the camera to where the application thinks it is\&. There is no default\&.
.RE
.PP
\fBkey_toggle\fR
.RS 4
This key alternately releases and recaptures the mouse\&. It can be useful if you need to use the mouse in another window without completely disabling the filter\-set (which would also restore the camera position)\&. There is no default\&.
.RE
.PP
.RS 4
This toggles display of the original view frustum\&. If this driver supports
GL_NV_depth_clamp, depth clamping is used to prevent the frustum from being clipped to the near and far clip planes\&. There is no default\&.
.RE
.SH "AUTHOR"
.PP
bugle
is written and maintained by
Bruce Merry\&.
.SH "SEE ALSO"
.PP
\fBbugle\fR(3)
